The World of Computer Software/The World of Computer Software.iso/vgx3.zip/VGX.DOC

Text File | 1993-01-06 | 15KB | 353 lines

                               VGX

                  A VGA Graphics file format for
                 QuickBASIC and Professional BASIC
                           Programmers

                     Version 3.0, January, 1993


                           USER MANUAL



Speed, speed, speed is what we want when loading a graphics file. Second
only to speed is compressed file size.  Also desirable is ease of use.

Well, welcome to VGX!  You have received an efficient, fast, and compressed
VGA graphics file format for your BASIC programs that is remarkably easy to
use. It may also be the fastest VGA hi-res graphics file loader on the
market!


First, let's get a few preliminaries behind us:

LICENSE AGREEMENT:

All files on the VGX distribution disk are (C) Copyright, 1990-93, Dwain
Goforth, Milestone Software, Arcata, California.  All rights reserved.

This software package (VGX30.ZIP and associated files) is for review
purposes only.  No license is granted for distribution of this software or
software created using the VGX object libraries.  The single exception to
this is that the original .ZIP distribution package may be distributed
provided no changes are made to any of the enclosed files.

The VGX package comes with three types of files, 1) compiled object code in
libraries (files with the .LIB extension), 2) executable files (PCX2VGX.EXE
and VGXGRAB.COM), and 3) text and BASIC source code files (with extensions
of .DOC and .BAS)

Upon registration, you will be licensed to distribute executable (.EXE and
.COM) programs of your own creation that use the VGX object modules.  No
royalties or copyright acknowledgement are required.  You will also be
licensed to distribute PCX2VGX.EXE and VGXGRAB.EXE as long as they have not
been modified in any way.

You are prohibited from distributing the VGX object files and their
associated libraries, or any library you make containing the VGX object
files, unless you are transfering this license in its entirety and removing
all VGX object files and any libraries containing them from your computer
system.


WARRANTY:

Milestone Software makes no warranties or guarantees concerning use of this
shareware distribution package of VGX.  Registered users will be guaranteed
100% satisfaction for one year following postmark of registration.


REGISTERING THIS SOFTWARE:

By sending your registration fee for this software you will be licensed to
distribute executable programs created with the VGX object libraries, and
begin your one-year money-back warranty.

The registration cost is $20 (US funds only.)  Checks or money orders may be
sent to Dwain Goforth, Milestone Software, 1260 Sunset Ave., Arcata,
California, 95521. Canadian residents are encouraged to use Canadian Postal
Money Orders which save you money in bank fees. All other checks and money
orders must be drawn on a US bank.

Please note that this fee is modest considering the effort that has been put
into developing VGX. If you distribute executable files containing VGX or
object files (including libraries) other than this ZIP package you can
expect to fork over your profits to me, as well as punitive damages and
lawyer fees.


                  ----------------------------------

FILES ON THE VGX DISK:

The following files are included on the VGX distribution disk:

     VGX.DOC     -    This file, the VGX manual.
     VGXSPEC.DOC -    Specifications of the VGX format.

     VGXN.LIB    -    Library for BASIC 7.0 using NEAR strings.
     VGXF.LIB    -    Library for BASIC 7.0 using FAR strings.

     VGXF.QLB    -    BASIC 7.0 (QBX.EXE) quicklibrary (far
                      strings.)

     PALCALLS.BAS  -  VGA palette routines.

     VGXTEST.BAS    -    BASIC source code to demonstrate VGX and
                         palette calls.
     VGXVIEW.BAS    -    BASIC source code to view VGX files.

     PCX2VGX.EXE    -    Program to convert PCX to VGX.

     VGXGRAB.COM    -    TSR (memory resident) program to capture
                         VGA SCREEN 12 (640x480x16) to a VGX file.

                   -------------------------

INTRODUCTION - What is VGX?

VGX is a new graphics file format for use by Microsoft PDS BASIC 7.x
programmers.  VGX supports ONLY the VGA 640x480 pixel 16-color graphics mode
(SCREEN 12), and because of this it is very fast.

If you've ever programmed VGA graphics files using the BASIC BSAVE/BLOAD
commands you know that even the least complex image requires 153k of disk
space in FOUR separate files.  Also, your palette is not saved.  While BLOAD
is fast, the file sizes, number of files and lack of palette are enough to
make one think twice before developing a VGA image program in BASIC.


HOW DOES VGX WORK?:

VGX is similar to BLOAD/BSAVE in that images are stored in "banks" just like
the VGA video memory stores them.  Each bank represents one color (red,
blue, green and intensity) and each bit in the bank is either on or off and
represents each pixel.  A VGA 640x480 16-color screen uses 152k of video RAM
with each bank using 38k.

VGX is similar to PCX in that it uses a "run-length" encoding scheme to
compress the data.  The PCX format compresses a screen one scan line at a
time (there are 480 scan lines in a VGA 640x480), while VGX compresses an
entire bank at a time.  When a run of the same byte pattern is encountered
in a color bank, VGX stores a count for them instead of the actual data.
Because banks are a series of 1's and 0's (on and off), the VGX compression
of an entire bank is usually quite efficient.  VGX switches banks four times
for each file, PCX switches banks four times for each scan line (1920 times
per file!)

The VGA adapter stores the palette in 16 byte-triplets (one byte for each
color; 48 bytes total.)  VGX simply gets this data from the VGA BIOS and
adds it to the VGX file.  Included is a BASIC program, PALCALLS.BAS which
will demonstrate the BIOS palette calls, show how to "fade" the 48-byte
palette data, and also how to rotate the palette ("palette animation".)

The VGXSave routine works by moving a VGA bank into RAM, compressing the
data into an array and saving the compressed array as a temporary file.
This is repeated three times, then the temporary files are appended together
along with the palette information.  The temporary files are then erased. In
the unlikely event that your computer crashes during a VGXSave session, you
may find these temporary files on your directory (filename.VX1 to
filename.VX4). They can be erased.

Because VGXSave copies an image of a bank and allocates an array to hold the
compressed data, VGXSave needs 74k of available RAM to work. This RAM is
allocated at the beginning of each VGXSave call and released at the end of
each call.

VGXLoad works in an opposite manner to VGXSave; a 16k file-load buffer is
created as well as an 38k array to hold an uncompressed bank.  The
decompression algorithm works on one buffer's worth of data at a time,
filling the bank array.  When a bank is full, it is transfered to video RAM.
When a buffer is used up, another is gotten from the disk. Depending on
which option you choose to load a VGX image (fade-in, instant on, etc...),
the palette is processed before or after the actual load.

Because VGXLoad uses a 16k file buffer and a 38k bank array, VGXLoad
requires 54k of free RAM to work. This RAM is allocated at the start of each
VGXLoad call and released at the end.  The 16k buffer size was chosen as the
optimum in a tradeoff between loading speed and minimizing RAM use.  (An
earlier, pre-release version of VGXLoad had a self-allocating buffer of 2k
to 64k, but a "hard-wired" size proved to be faster.)

A number of algorithms were considered for the VGX compression. All of them
pose a tradeoff between compressed file size and speed of loading. And while
greater compression is obtainable, the vast superiority in speed of the
bank-load/run-length compression method left all other options in the dust.

             -----------------------------------------

                             USING VGX

The VGX file format is very easy to use in your QuickBASIC programs.  You
simply add VGXx.LIB to your normal quicklibrary or use the supplied VGX
quicklibrary.  To create a stand-alone EXE file you link your program's
object file (created with BC) with VGXx.LIB.

Once in QB, you simply CALL VGXSave (filname$) to save a file or CALL
VGXLoad (filname$, palflag%) to load a file.

The most IMPORTANT thing to remember is filname$ MUST be just the first
eight letters of the filename (no extension.) Thus VGXSave("TEST") will work
fine, but VGXSave("TEST.VGX") will fail.

There is no error catching in VGXSave or VGXLoad. Every effort has been made
to return control to your calling program without crashing, but speed was
the overriding consideration. You will have to make sure that the syntax is
correct and valid filenames are used BEFORE call VGXLoad or VGXSave.

Libraries and Quicklibraries:

I have assumed that you already have your own personal library and
quicklibrary to which you will want to add VGXx.LIB.  To do so, type the
following at the DOS prompt:

     LIB yourname.lib +VGXx.LIB;

     LINK /q yourname.lib

     At the "Library" prompt type "QBXQLB"

     (Remember that you cannot make a near-string quicklibrary using
     VGXN.LIB, you have to use far strings in the QBX environment.)


USING VGXSave:

Once in QB with a quicklibrary loaded containing VGX you may call VGXSave
and VGXLoad.  Prior to either call you MUST have entered VGA 640x480
16-color graphics mode (SCREEN 12).  The syntax to call VGXSave is as
follows:

     CALL VGXSave(filnam$)

IMPORTANT!!! -->  Please note that "filnam$" DOES NOT include the extension,
thus to make a VGX file named "TEST.VGX" you CALL VGXSave("test"), the
extension will be added by VGXSave itself.

Or...

     fil$="test"
     CALL VGXSave(fil$)

You may also pass a path...

     fil$="C:\graphics\vgx\test"
     CALL VGXSave(fil$)

To be on the safe side, your disk should have 153k of free space for the
maximum size of any potential VGX file.


USING VGXLoad:

The VGXLoad routine has two parameters and is called as follows:

     CALL VGXLoad(Fil$, Flag%)

Again, DO NOT use a filename extension for Fil$.

Flag% is the parameter to choose one of five loading options, from "instant
on" to "fade-in".

Flag% may range from 0 to 4.  The following table shows the action for the
Flag% options:

          action for          action for
          current             screen being
Flag%     screen              loaded
----------------------------------------------
  0       no blank            bank load
  1       blank to color 0    instant on
  2       blank to color 0    fade in
  3       fade out            instant on
  4       fade out            fade in

If Flag is 0 then the current image gets replaced one bank at a time, as
soon as they are ready.  This is the fastest method to load a VGX screen.
It is very much like BLOADing.

If Flag is 1 or 2 then the current image is cleared to its current
background color (whatever color is assigned to attribute 0).

If Flag is 3 or 4 then the palette for the current image is faded by
changing each attribute closer to attribute 0 (color 0) in a 64 count loop.

For the VGX screen you are loading "instant on" is where the file is loaded
into video RAM while all the colors are set to attribute zero and then DOS
is called to set the actual palette that was stored in the file.  This
method of setting the palette is very fast, much faster than using BASIC's
PALETTE statements.  See PALCALLS.BAS for the syntax used in VGXLoad.

"Fade in" makes a 64 count loop, gradually changing the colors from
attribute zero to their correct value.


RUNNING PCX2VGX.EXE:

If you have PCX files in 640x480 16-color format you can convert them to VGX
format using PCX2VGX.  PCX2VGX will convert the file, test load it, and even
test the gray-scale color balance (to see how your image will look on a
monochrome VGA display.)

Please note that ONLY 640x480 16-color PCX files will convert correctly with
PCX2VGX.

Type `PCX2VGX filename' or 'PCX2EGX filename' at the DOS prompt, DO NOT
include any filename extension in `filename'.


RUNNING VGXGRAB.COM:

VGXGRAB is a TSR (memory resident) program that will dump whatever is on
your VGA 640x480 16-color screen to a VGX file. Type VGXGRAB at the DOS
prompt and it will become resident. VGXGRAB will allocate approximately 80k
of RAM while resident. Some paint programs that require a full 640k to run
will not run when VGXGRAB is resident (you will get an "insufficient memory"
error) In that event, hopefully, your paint program will save to a PCX file
format which you can then convert to VGX using PCX2VGX.

After VGXGRAB is resident, run whatever screen display program you wish to
capture from (VGXVIEW and VGXDEMO will work if you are just testing) and hit
the "hotkey" to save the image to a VGX format file.  The hotkey is
CTRL/ENTER (both the "Control" and "Enter" keys pressed at the same time.)
After the VGX file is saved you will hear a short beep and control will
return to your display program.

VGX files saved by VGXGRAB are named VGXxxx.VGX where xxx is a number, so
the first VGX file you create with VGXGRAB will be VGX1.VGX, the second,
VGX2.VGX, and so on.  If a VGX file with the same name already exists, that
number will be skipped, so, for example, if VGX1.VGX and VGX2.VGX already
exist on the default directory, then the fist file VGXGRAB will save is
VGX3.VGX, etc...

VGXGRAB cannot be removed from memory.  In other words you must reboot your
computer to remove them.  I have attempted to create removable TSR's (and
will continue to try) but so far they are quite buggy and I would rather be
safe than sorry.

Please remember that VGXGRAB is designed specifically for the 640x480x16
graphics modes.  Using it with other modes will give unpredictable results
(i.e., garbage.)

                          - - - - - - -

In summary, remember you have three ways to create a VGX file, 1) in QB (or
your compiled EXE) using VGXSave, 2) converting PCX files using PCX2VGX, and
3) running the TSR program, VGXGRAB and capturing screens while in another
program.

Please see "Optimizing VGX Files" in the VGXSPECS.DOC file for tips on how
to make your VGX files as small and efficient as possible.

                  --------------------------------

Thank you for trying VGX.  Please feel free to call or write with any
questions or comments.

Dwain Goforth
Milestone Software
1260 Sunset Ave.
Arcata, CA 95521 USA
[phone]